home *** CD-ROM | disk | FTP | other *** search
/ Amiga Format CD 52 / Amiga Format AFCD52 (Issue 136, May 2000).iso / -serious- / programming / c / icu-1.3.1 / icu-bin / include / uloc.h < prev    next >
C/C++ Source or Header  |  2000-02-23  |  17KB  |  479 lines
  1. /*
  2. ********************************************************************************
  3. *                                                                              *
  4. * COPYRIGHT:                                                                   *
  5. *   (C) Copyright Taligent, Inc.,  1997                                        *
  6. *   (C) Copyright International Business Machines Corporation,  1997-1999      *
  7. *   Licensed Material - Program-Property of IBM - All Rights Reserved.         *
  8. *   US Government Users Restricted Rights - Use, duplication, or disclosure    *
  9. *   restricted by GSA ADP Schedule Contract with IBM Corp.                     *
  10. *                                                                              *
  11. ********************************************************************************
  12. *
  13. * File ULOC.H
  14. *
  15. * Modification History:
  16. *
  17. *   Date        Name        Description
  18. *   04/01/97    aliu        Creation.
  19. *   08/22/98    stephen     JDK 1.2 sync.
  20. *   12/08/98    rtg         New C API for Locale
  21. *   03/30/99    damiba      overhaul
  22. *   03/31/99    helena      Javadoc for uloc functions.
  23. *   04/15/99    Madhu       Updated Javadoc
  24. ********************************************************************************
  25. */
  26.  
  27. #ifndef ULOC_H
  28. #define ULOC_H
  29.  
  30. #include "utypes.h"
  31.  
  32. /**    
  33.  *
  34.  * A <code>Locale</code> represents a specific geographical, political,
  35.  * or cultural region. An operation that requires a <code>Locale</code> to perform
  36.  * its task is called <em>locale-sensitive</em> and uses the <code>Locale</code>
  37.  * to tailor information for the user. For example, displaying a number
  38.  * is a locale-sensitive operation--the number should be formatted
  39.  * according to the customs/conventions of the user's native country,
  40.  * region, or culture.  In the C APIs, a locales is simply a const char string.
  41.  *
  42.  * <P>
  43.  * You create a <code>Locale</code> with one of the three options listed below.
  44.  * Each of the component is separated by '_' in the locale string.
  45.  * <blockquote>
  46.  * <pre>
  47.  * .      newLanguage
  48.  * .
  49.  * .      newLanguage + newCountry
  50.  * .
  51.  * .      newLanguage + newCountry + newVariant
  52.  * </pre>
  53.  * </blockquote>
  54.  * The first option is a valid <STRONG>ISO
  55.  * Language Code.</STRONG> These codes are the lower-case two-letter
  56.  * codes as defined by ISO-639.
  57.  * You can find a full list of these codes at a number of sites, such as:
  58.  * <BR><a href ="http://www.ics.uci.edu/pub/ietf/http/related/iso639.txt">
  59.  * <code>http://www.ics.uci.edu/pub/ietf/http/related/iso639.txt</code></a>
  60.  *
  61.  * <P>
  62.  * The second option includes an additonal <STRONG>ISO Country
  63.  * Code.</STRONG> These codes are the upper-case two-letter codes
  64.  * as defined by ISO-3166.
  65.  * You can find a full list of these codes at a number of sites, such as:
  66.  * <BR><a href="http://www.chemie.fu-berlin.de/diverse/doc/ISO_3166.html">
  67.  * <code>http://www.chemie.fu-berlin.de/diverse/doc/ISO_3166.html</code></a>
  68.  *
  69.  * <P>
  70.  * The third option requires another additonal information--the 
  71.  * <STRONG>Variant.</STRONG>
  72.  * The Variant codes are vendor and browser-specific.
  73.  * For example, use WIN for Windows, MAC for Macintosh, and POSIX for POSIX.
  74.  * Where there are two variants, separate them with an underscore, and
  75.  * put the most important one first. For
  76.  * example, a Traditional Spanish collation might be referenced, with
  77.  * "ES", "ES", "Traditional_WIN".
  78.  *
  79.  * <P>
  80.  * Because a <code>Locale</code> is just an identifier for a region,
  81.  * no validity check is performed when you specify a <code>Locale</code>.
  82.  * If you want to see whether particular resources are available for the
  83.  * <code>Locale</code> you asked for, you must query those resources. For
  84.  * example, ask the <code>UNumberFormat</code> for the locales it supports
  85.  * using its <code>getAvailable</code> method.
  86.  * <BR><STRONG>Note:</STRONG> When you ask for a resource for a particular
  87.  * locale, you get back the best available match, not necessarily
  88.  * precisely what you asked for. For more information, look at
  89.  * <a href="ures.html"><code>UResourceBundle</code></a>.
  90.  *
  91.  * <P>
  92.  * The <code>Locale</code> provides a number of convenient constants
  93.  * that you can use to specify the commonly used
  94.  * locales. For example, the following refers to a locale
  95.  * for the United States:
  96.  * <blockquote>
  97.  * <pre>
  98.  * .      ULOC_US
  99.  * </pre>
  100.  * </blockquote>
  101.  *
  102.  * <P>
  103.  * Once you've specified a locale you can query it for information about
  104.  * itself. Use <code>uloc_getCountry</code> to get the ISO Country Code and
  105.  * <code>uloc_getLanguage</code> to get the ISO Language Code. You can
  106.  * use <code>uloc_getDisplayCountry</code> to get the
  107.  * name of the country suitable for displaying to the user. Similarly,
  108.  * you can use <code>uloc_getDisplayLanguage</code> to get the name of
  109.  * the language suitable for displaying to the user. Interestingly,
  110.  * the <code>uloc_getDisplayXXX</code> methods are themselves locale-sensitive
  111.  * and have two versions: one that uses the default locale and one
  112.  * that takes a locale as an argument and displays the name or country in
  113.  * a language appropriate to that locale.
  114.  *
  115.  * <P>
  116.  * The ICU provides a number of services that perform locale-sensitive
  117.  * operations. For example, the <code>unum_xxx</code> functions format
  118.  * numbers, currency, or percentages in a locale-sensitive manner. 
  119.  * </P>
  120.  * <blockquote>
  121.  * <pre>
  122.  * .    UErrorCode success = U_ZERO_ERROR;
  123.  * .    UNumberFormat *nf;
  124.  * .    const char* myLocale = "fr_FR";
  125.  * .
  126.  * .    nf = unum_open( UNUM_DEFAULT, NULL, success );          
  127.  * .    unum_close(nf);
  128.  * .    nf = unum_open( UNUM_CURRENCY, NULL, success );
  129.  * .    unum_close(nf);
  130.  * .    nf = unum_open( UNUM_PERCENT, NULL, success );   
  131.  * .    unum_close(nf);
  132.  * </pre>
  133.  * </blockquote>
  134.  * Each of these methods has two variants; one with an explicit locale
  135.  * and one without; the latter using the default locale.
  136.  * <blockquote>
  137.  * <pre>
  138.  * .
  139.  * .    nf = unum_open( UNUM_DEFAULT, myLocale, success );          
  140.  * .    unum_close(nf);
  141.  * .    nf = unum_open( UNUM_CURRENCY, myLocale, success );
  142.  * .    unum_close(nf);
  143.  * .    nf = unum_open( UNUM_PERCENT, myLocale, success );   
  144.  * .    unum_close(nf);
  145.  * </pre>
  146.  * </blockquote>
  147.  * A <code>Locale</code> is the mechanism for identifying the kind of services
  148.  * (<code>UNumberFormat</code>) that you would like to get. The locale is
  149.  * <STRONG>just</STRONG> a mechanism for identifying these services.
  150.  *
  151.  * <P>
  152.  * Each international serivce that performs locale-sensitive operations 
  153.  * allows you
  154.  * to get all the available objects of that type. You can sift
  155.  * through these objects by language, country, or variant,
  156.  * and use the display names to present a menu to the user.
  157.  * For example, you can create a menu of all the collation objects
  158.  * suitable for a given language. Such classes implement these
  159.  * three class methods:
  160.  * <blockquote>
  161.  * <pre>
  162.  * .      const char* uloc_getAvailable(int32_t index);
  163.  * .      int32_t uloc_countAvailable();
  164.  * .      int32_t
  165.  * .      uloc_getDisplayName(const char* localeID,
  166.  * .                const char* inLocaleID, 
  167.  * .                UChar* result,
  168.  * .                int32_t maxResultSize,
  169.  * .                 UErrorCode* err);
  170.  * .
  171.  * </pre>
  172.  * </blockquote>
  173.  */
  174.  
  175. /**
  176.  *
  177.  * Useful constants for language.
  178.  */
  179. #define ULOC_ENGLISH "en"
  180. #define ULOC_FRENCH "fr"
  181. #define ULOC_GERMAN "de"
  182. #define ULOC_ITALIAN "it"
  183. #define ULOC_JAPANESE "ja"
  184. #define ULOC_KOREAN "ko"
  185. #define ULOC_CHINESE "zh"
  186. #define ULOC_SIMPLIFIED_CHINESE "zh_CN"
  187. #define ULOC_TRADITIONAL_CHINESE "zh_TW"
  188.  
  189. /**
  190.  *
  191.  * Useful constants for country.
  192.  */
  193. #define ULOC_FRANCE "fr_FR"
  194. #define ULOC_GERMANY "de_DE"
  195. #define ULOC_ITALY "it_IT"
  196. #define ULOC_JAPAN "ja_JP"
  197. #define ULOC_KOREA "ko_KR"
  198. #define ULOC_CHINA "zh_CN"
  199. #define ULOC_PRC "zh_CN"
  200. #define ULOC_TAIWAN "zh_TW"
  201. #define ULOC_UK "en_GB"
  202. #define ULOC_US "en_US"
  203. #define ULOC_CANADA "en_CA"
  204. #define ULOC_CANADA_FRENCH "fr_CA"
  205.  
  206.  
  207.  
  208.  
  209. /**
  210.  *
  211.  * Gets the system's default locale.
  212.  * @return the system default locale
  213.  */
  214.  
  215. U_CAPI const char* U_EXPORT2
  216. uloc_getDefault(void);
  217.  
  218. /**
  219.  *
  220.  * Sets the system's default locale.
  221.  * @param localeID the new system default locale
  222.  * @param status the error information if the setting of default locale fails
  223.  */
  224. U_CAPI void U_EXPORT2
  225. uloc_setDefault(const char* localeID,
  226.         UErrorCode*       status);
  227.  
  228. /**
  229.  *
  230.  * Gets the language code for the specified locale.
  231.  * @param localeID the locale to get the ISO langauge code with
  232.  * @param language the langauge code for localeID
  233.  * @param languageCapacity the size of the language buffer to store the  
  234.  * language code with
  235.  * @param err error information if retrieving the  language code failed
  236.  * @return the actual buffer size needed for the  langauge code.  If it's greater 
  237.  * than languageCapacity, the returned language code will be truncated.  
  238.  */
  239.  
  240. U_CAPI int32_t U_EXPORT2
  241. uloc_getLanguage(const char*    localeID,
  242.          char* language,
  243.          int32_t languageCapacity,
  244.          UErrorCode* err);
  245.  
  246. /**
  247.  *
  248.  * Gets the  country code for the specified locale.
  249.  * @param localeID the locale to get the country code with
  250.  * @param country the country code for localeID
  251.  * @param languageCapacity the size of the coutry buffer to store the  
  252.  * country code with
  253.  * @param err error information if retrieving the country code failed
  254.  * @return the actual buffer size needed for the country code.  If it's greater 
  255.  * than countryCapacity, the returned country code will be truncated.  
  256.  */
  257.  
  258. U_CAPI int32_t U_EXPORT2
  259. uloc_getCountry(const char*    localeID,
  260.         char* country,
  261.         int32_t countryCapacity,
  262.         UErrorCode* err);
  263.  
  264. /**
  265.  *
  266.  * Gets the variant code for the specified locale.
  267.  * @param localeID the locale to get the variant code with
  268.  * @param variant the variant code for localeID
  269.  * @param variantCapacity the size of the variant buffer to store the 
  270.  * variant code with
  271.  * @param err error information if retrieving the variant code failed
  272.  * @return the actual buffer size needed for the variant code.  If it's greater 
  273.  * than variantCapacity, the returned variant code will be truncated.  
  274.  */
  275.  
  276. U_CAPI int32_t U_EXPORT2
  277. uloc_getVariant(const char*    localeID,
  278.         char* variant,
  279.         int32_t variantCapacity,
  280.         UErrorCode* err);
  281. /**
  282.  *
  283.  * Gets the full name for the specified locale.
  284.  * @param localeID the locale to get the full name with
  285.  * @param name the full name for localeID
  286.  * @param nameCapacity the size of the name buffer to store the 
  287.  * full name with
  288.  * @param err error information if retrieving the full name failed
  289.  * @return the actual buffer size needed for the full name.  If it's greater 
  290.  * than nameCapacity, the returned full name will be truncated.  
  291.  */
  292.  
  293. U_CAPI int32_t U_EXPORT2
  294. uloc_getName(const char*    localeID,
  295.          char* name,
  296.          int32_t nameCapacity,
  297.          UErrorCode* err);
  298.  
  299. /**
  300.  *
  301.  * Gets the ISO language code for the specified locale.
  302.  * @param localeID the locale to get the ISO langauge code with
  303.  * @return language the ISO langauge code for localeID
  304.  */
  305. U_CAPI const char* U_EXPORT2
  306. uloc_getISO3Language(const char* localeID);
  307.  
  308.  
  309. /**
  310.  *
  311.  * Gets the ISO country code for the specified locale.
  312.  * @param localeID the locale to get the ISO country code with
  313.  * @return country the ISO country code for localeID
  314.  */
  315.  
  316. U_CAPI const char* U_EXPORT2
  317. uloc_getISO3Country(const char* localeID);
  318.  
  319. /**
  320.  *
  321.  * Gets the Win32 LCID value for the specified locale.
  322.  * @param localeID the locale to get the Win32 LCID value with
  323.  * @return country the Win32 LCID for localeID
  324.  */
  325.  
  326. U_CAPI uint32_t U_EXPORT2
  327. uloc_getLCID(const char* localeID);
  328.  
  329. /**
  330.  *
  331.  * Gets the language name suitable for display for the specified locale.
  332.  * @param localeID the locale to get the ISO langauge code with
  333.  * @param language the displayable langauge code for localeID
  334.  * @param languageCapacity the size of the language buffer to store the  
  335.  * displayable language code with
  336.  * @param err error information if retrieving the displayable language code failed
  337.  * @return the actual buffer size needed for the displayable langauge code.  If it's greater 
  338.  * than languageCapacity, the returned language code will be truncated.  
  339.  */
  340. U_CAPI int32_t U_EXPORT2
  341. uloc_getDisplayLanguage(const char* locale,
  342.             const char* inLocale,
  343.             UChar* language,
  344.             int32_t languageCapacity,
  345.             UErrorCode* status);
  346.  
  347. /**
  348.  *
  349.  * Gets the country name suitable for display for the specified locale.
  350.  * @param localeID the locale to get the displayable country code with
  351.  * @param country the displayable country code for localeID
  352.  * @param languageCapacity the size of the coutry buffer to store the  
  353.  * displayable country code with
  354.  * @param err error information if retrieving the displayable country code failed
  355.  * @return the actual buffer size needed for the displayable country code.  If it's greater 
  356.  * than countryCapacity, the returned displayable country code will be truncated.  
  357.  */
  358.  
  359. U_CAPI int32_t U_EXPORT2
  360. uloc_getDisplayCountry(const char* locale,
  361.             const char* inLocale,
  362.             UChar* country,
  363.             int32_t countryCapacity,
  364.             UErrorCode* status);    /* NULL may be used to specify the default */
  365.  
  366.  
  367. /**
  368.  *
  369.  * Gets the variant code suitable for display for the specified locale.
  370.  * @param localeID the locale to get the displayable variant code with
  371.  * @param variant the displayable variant code for localeID
  372.  * @param variantCapacity the size of the variant buffer to store the 
  373.  * displayable variant code with
  374.  * @param err error information if retrieving the displayable variant code failed
  375.  * @return the actual buffer size needed for the displayable variant code.  If it's greater 
  376.  * than variantCapacity, the returned displayable variant code will be truncated.  
  377.  */
  378.  
  379. U_CAPI int32_t U_EXPORT2
  380. uloc_getDisplayVariant(const char* locale,
  381.             const char* inLocale,
  382.                UChar* variant,
  383.              int32_t variantCapacity,
  384.             UErrorCode* status);    /* NULL may be used to specify the default */
  385.  
  386. /**
  387.  *
  388.  * Gets the full name suitable for display for the specified locale.
  389.  * @param localeID the locale to get the displayable name with
  390.  * @param variant the displayable name for localeID
  391.  * @param variantCapacity the size of the name buffer to store the 
  392.  * displayable full name with
  393.  * @param err error information if retrieving the displayable name failed
  394.  * @return the actual buffer size needed for the displayable name.  If it's greater 
  395.  * than variantCapacity, the returned displayable name will be truncated.  
  396.  */
  397.  
  398. U_CAPI int32_t U_EXPORT2
  399. uloc_getDisplayName(const char* localeID,
  400.             const char* inLocaleID, /* NULL may be used to specify the default */
  401.             UChar* result,
  402.             int32_t maxResultSize,
  403.             UErrorCode* err);
  404.  
  405.  
  406. /**
  407.  *
  408.  * Gets the specified locale from a list of all available locales.  
  409.  * The return value is a pointer to an item of 
  410.  * a locale name array.  Both this array and the pointers
  411.  * it contains are owned by ICU and should not be deleted or written through
  412.  * by the caller.  The locale name is terminated by a null pointer.
  413.  * @param index the specific locale name index of the available locale list
  414.  * @return a specified locale name of all available locales
  415.  */
  416. U_CAPI const char* U_EXPORT2
  417. uloc_getAvailable(int32_t index);
  418.  
  419. /**
  420.  *
  421.  * Gets the size of the all available locale list.
  422.  * @return the size of the locale list
  423.  */
  424. U_CAPI int32_t U_EXPORT2 uloc_countAvailable(void);
  425.  
  426. /**
  427.  *
  428.  * Gets a list of all available language codes defined in ISO 639.  This is a pointer
  429.  * to an array of pointers to arrays of char.  All of these pointers are owned
  430.  * by ICU-- do not delete them, and do not write through them.  The array is
  431.  * terminated with a null pointer.
  432.  * @return a list of all available language codes
  433.  */
  434. U_CAPI const char* const* U_EXPORT2
  435. uloc_getISOLanguages(void);
  436.  
  437. /**
  438.  *
  439.  * Gets a list of all available 2-letter country codes defined in ISO 639.  This is a
  440.  * pointer to an array of pointers to arrays of char.  All of these pointers are
  441.  * owned by ICU-- do not delete them, and do not write through them.  The array is
  442.  * terminated with a null pointer.
  443.  * @return a list of all available country codes
  444.  */
  445. U_CAPI const char* const* U_EXPORT2
  446. uloc_getISOCountries(void);
  447.  
  448. /**
  449.  *
  450.  * Gets the directory containing the locale data files.
  451.  * @return the locale data file directory
  452.  */
  453. U_CAPI const char* U_EXPORT2
  454. uloc_getDataDirectory(void);
  455.  
  456. /**
  457.  *
  458.  * Sets the directory containing the locale data files.
  459.  * @return the new directory to fetch locale data from
  460.  */
  461.  
  462. U_CAPI void U_EXPORT2
  463. uloc_setDataDirectory(const char* newDirectory);
  464.  
  465. /*Internal function */
  466. int32_t U_EXPORT2
  467. uloc_getParent(const char*    localeID,
  468.                  char* parent,
  469.                  int32_t parentCapacity,
  470.                  UErrorCode* err);
  471.  
  472. /*eof*/
  473.  
  474.  
  475. #endif /*_ULOC*/
  476.  
  477.  
  478.  
  479.